 /*******************************************************************************
  * Copyright (c) 2004, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.core.internal.localstore;

 import java.io.InputStream ;
 import java.util.Set ;
 import org.eclipse.core.filesystem.IFileInfo;
 import org.eclipse.core.filesystem.IFileStore;
 import org.eclipse.core.internal.resources.IManager;
 import org.eclipse.core.resources.IFileState;
 import org.eclipse.core.resources.IResource;
 import org.eclipse.core.runtime.*;

 /**
  * The history store is an association of paths to file states.
  * Typically the path is the full path of a resource in the workspace.
  * <p>
  * History store policies are stored in the org.eclipse.core.resources'
  * plug-in preferences.
  * </p>
  *
  * @since 3.1
  */
 public interface IHistoryStore extends IManager {

     /**
      * Add an entry to the history store, represented by the given key. Return the
      * file state for the newly created entry or<code>null</code> if it couldn't
      * be created.
      * <p>
      * Note: Depending on the history store implementation, some of the history
      * store policies can be applied during this method call to determine whether
      * or not the entry should be added to the store.
      * </p>
      * @param key full workspace path to resource being logged
      * @param localFile local file system file handle
      * @param fileInfo The IFileInfo for the entry
      * @return the file state or <code>null</code>
      *
      * TODO: should this method take a progress monitor?
      *
      * TODO: look at #getFileFor(). Is there a case where we wouldn't want to
      * copy over the file attributes to the local history? If we did that here then
      * we wouldn't have to have that other API.
      */
     public IFileState addState(IPath key, IFileStore localFile, IFileInfo fileInfo, boolean moveContents);

     /**
      * Returns the paths of all files with entries in this history store at or below
      * the given workspace resource path to the given depth. Returns an
      * empty set if there are none.
      * <p>
      * This method is long-running; progress and cancellation are provided
      * by the given progress monitor.
      * </p>
      * @param path full workspace path to resource
      * @param depth depth limit: one of <code>DEPTH_ZERO</code>, <code>DEPTH_ONE</code>
      * or <code>DEPTH_INFINITE</code>
      * @param monitor a progress monitor, or <code>null</code> if progress
      * reporting is not desired
      * @return the set of paths for files that have at least one history entry
      * (element type: <code>IPath</code>)
      */
     public Set allFiles(IPath path, int depth, IProgressMonitor monitor);

     /**
      * Clean this store applying the current policies.
      * <p>
      * Note: The history store policies are stored as part of
      * the org.eclipse.core.resource plug-in's preferences and
      * include such settings as: maximum file size, maximum number
      * of states per file, file expiration date, etc.
      * </p>
      * <p>
      * Note: Depending on the implementation of the history store,
      * if all the history store policies are applying when the entries
      * are first added to the store then this method might be a no-op.
      * </p>
      * <p>
      * This method is long-running; progress and cancellation are provided
      * by the given progress monitor.
      * </p>
      * @param monitor a progress monitor, or <code>null</code> if progress
      * reporting is not desired
      */
     public void clean(IProgressMonitor monitor);

     /**
      * Closes the history store for the given resource.
      */
     public void closeHistoryStore(IResource resource);
     
     /**
      * Copies the history store information from the source path given destination path.
      * Note that destination may already have some history store information. Also note
      * that this is a DEPTH_INFINITY operation. That is, history will be copied for partial
      * matches of the source path.
      *
      * @param source the resource containing the original copy of the history store information
      * @param destination the target resource where to copy the history
      * @param moving whether the history is being copied due to a resource move
      *
      * TODO: should this method take a progress monitor?
      */
     public void copyHistory(IResource source, IResource destination, boolean moving);

     /**
      * Verifies existence of specified resource in the history store. Returns
      * <code>true</code> if the file state exists and <code>false</code>
      * otherwise.
      * <p>
      * Note: This method cannot take a progress monitor since it is surfaced
      * to the real API via IFileState#exists() which doesn't take a progress
      * monitor.
      * </p>
      * @param target the file state to be verified
      * @return <code>true</code> if file state exists,
      * and <code>false</code> otherwise
      */
     public boolean exists(IFileState target);

     /**
      * Returns an input stream containing the file contents of the specified state.
      * The user is responsible for closing the returned stream.
      * <p>
      * Note: This method cannot take a progress monitor since it is
      * surfaced through to the real API via IFileState#getContents which
      * doesn't take one.
      * </p>
      * @param target File state for which an input stream is requested
      * @return the stream for requested file state
      */
     public InputStream getContents(IFileState target) throws CoreException;

     /**
      * Returns an array of all states available for the specified resource path or
      * an empty array if none.
      * <p>
      * This method is long-running; progress and cancellation are provided
      * by the given progress monitor.
      * </p>
      * @param path the resource path
      * @param monitor a progress monitor, or <code>null</code> if progress
      * reporting is not desired
      * @return the list of file states
      */
     public IFileState[] getStates(IPath path, IProgressMonitor monitor);

     /**
      * Remove all of the file states for the given resource path and
      * all its children. If the workspace root path is the given argument,
      * then all history for this store is removed.
      * <p>
      * This method is long-running; progress and cancellation are provided
      * by the given progress monitor.
      * </p>
      * @param path the resource path whose history is to be removed
      * @param monitor a progress monitor, or <code>null</code> if progress
      * reporting is not desired
      */
     public void remove(IPath path, IProgressMonitor monitor);

     /**
      * Go through the history store and remove all of the unreferenced states.
      *
      * As of 3.0, this method is used for testing purposes only. Otherwise the history
      * store is garbage collected during the #clean method.
      */
     public void removeGarbage();
 }

